Documentation Section

Sample section object

Below we have included ONE of the sections normally added for the default Docular documenation

module.exports = function(grunt) {

    // Project configuration
    grunt.initConfig({

        pkg: grunt.file.readJSON('package.json'),

        docular: {
            groups: [
                {
                    groupTitle: 'Docular',
                    groupId: 'docular',
                    groupIcon: 'icon-beer',
                    sections: [
                        {
                            id: "docularinstall",
                            title: "Install Docular",
                            showSource: false,
                            docs: [
                                "lib/scripts/docs/install"
                            ],
                            rank: {
                                'installnode':1,
                                'installgrunt':2,
                                'installdocular':3
                            }
                        },
                        //the rest of the section objects ommitted
                    ]
                }
            ],
            //other configurations ommitted here for simplicity
        }

    });

    // Load the plugin that provides the "docular" tasks.
    grunt.loadNpmTasks('grunt-docular');

    // Default task(s).
    grunt.registerTask('default', ['docular']);

};

The difference between Docs and Scripts

We provide two buckets, "docs", and "scripts" as configurations within a section object. You can certainly use both within one section but understanding the difference is important.

Every directory or filename specified within the "docs" array will be parsed for documentation that exists NOT within comments in that file. So "docs" files are meant to basically be non-code files with "overview" or "tutorial" type information. Doc files are there for providing a more convient way of creating documentation that doesn't necessarily depend on actual code.

As of this writing, all "doc" files should have a ".doc" or ".ngdoc" extension.

If you specify a file or directory within the "scripts" array, those files will all be scanned for documentation WITHIN block comments. This is a great way to add documentation inline and near your actual code.

There is a lot of flexibility so just follow what works for your project.

Group Configuration for Docular

{
    groupTitle: 'Docular',
    groupId: 'docular',
    groupIcon: 'icon-edit',
    descr: 'Description',
    showSource: true,
    sections: [
        {
            id: "docularinstall",
            title: "Install Docular",
            docs: [
                "lib/scripts/docs/install"
            ],
            rank: {
                'installnode':1,
                'installgrunt':2,
                'installdocular':3
            }
        },
        {
            id: "docularconfigure",
            title: "Docular Configurations",
            docs: [
                "lib/scripts/docs/configure"
            ],
            rank: {
                'show':1,
                'groups':2,
                'sections':3,
                'discussions':4,
                'analytics':5,
                'partials':6,
                'ui':7
            }
        },
        {
            id: "docularcreate",
            title: "Documentation Groups and Sections",
            docs: [
                "lib/scripts/docs/create"
            ],
            rank: {'configuregroup':1, 'configuresection':2, 'firstdoc':3}
        },
        {
            id: "embed",
            title: "Embedding Documentation",
            docs: [
                "lib/scripts/docs/embed"
            ],
            rank: {'blockdef_js':1, 'blockdef_doc':2}
        },
        {
            id: 'basics',
            title: 'Documentation Basics',
            docs: [
                "lib/scripts/docs/basics"
            ],
            rank : {
                'identifier':1,
                'naming':2,
                'fields':3,
                'modules':4,
                'sections':5,
                'types':6,
                'types_doc':7,
                'types_ngdoc':8,
                'children':9,
                'links':10
            }
        },
        {
            id: "doctypes",
            title: 'Documentation Types (DocTypes)',
            docs: [
                "lib/scripts/docs/doctypes/doctypes.doc"
            ],
            rank : {'types_doc':2, 'types_ngdoc':3}
        },
        {
            id: "docularext",
            title:"Docular Extensions",
            scripts: [],
            docs: [
                "lib/scripts/docs/extensions"
            ]
        },
        {
            id: "docular",
            title:"Docular Source",
            scripts: [
                "lib/scripts/gen-docs.js",
                "lib/scripts/reader.js",
                "lib/scripts/writer.js",
                "lib/scripts/Doc.js"
            ],
            docs : [
                "lib/scripts/docs/node",
                "README.md"
            ]
        },
        {
            id: "docularfaq",
            title:"FAQs",
            scripts: [],
            docs: [
                "lib/scripts/docs/faq"
            ]
        }
    ]
}

Group Configuration for AngularJS Source

We made some small tweaks, but ported over most of the AngularJS "scripts" and "docs" in tact.

{
    groupTitle: 'Angular',
    groupId: 'angular',
    groupIcon: 'icon-book',
    sections: [
        {
            id: "api",
            title:"Angular API",
            scripts: ["lib/angular/js"]
        },
        {
            id: "guide",
            title: "Developers Guide",
            docs: ["lib/angular/ngdocs/guide"]
        },
        {
            id: "tutorial",
            title: "Tutorial",
            docs: ["lib/angular/ngdocs/tutorial"]
        },
        {
            id: "misc",
            title: "Overview",
            docs: ["lib/angular/ngdocs/misc"]
        }
    ]
}